前面兩篇我們已經介紹完資料庫操作，可能有朋友會疑問 API 細節是如何進行實現，為什麼我們在 程式中加入 @RestController、@GetMapping 就可以實作一個 API 進行呼叫，甚至好奇什麼是 API，這篇將來解釋 API 實作細節並介紹 RESTful API 設計風格。

API 的基本介紹我想可以直接參考這篇文章，作者提到的 API 概念非常清晰，我們整理內容大概描述，應用程式介面（Application Programming Interface, API）是扮演應用程式與應用程式之間溝通的橋樑，以幫助使用者達到目的為目標導向，讓使用者在操作 API 的過程，不需要知道內部程式運作的邏輯，只要告訴 API 你的需求，即可達到目的。

而 API 常見設計的風格有 REST、GraphQL、gRPC和 Webhooks，我們在這篇會先提到目前普遍率最高的 RESTful API來介紹。REST 全名為 Representational State Transfer( 表現層狀態轉移)，是此段開頭提到的其中一種 API 設計風格，而 RESTful 只是將 REST 轉為形容詞，一般在設計 Restful API 我們會通常會考慮四個重要觀念，如下：

1. Nouns 名詞

   API Endpoint 必須使用 名詞 進行定義 URL，而每個資源都要保持唯一性，資源採用複數命名，例如學生資料就是 /students

2. Verbs 動詞

   利用 Verbs 動詞 對 Nouns 名詞 (資源 URL) 進行操作，在 HTTP 1.1 的實作就是 HTTP Method，即 Get、Post、Put、Delete、Patch等，例如使用 Get Method 取得學生資料、用 Delete Method 刪除學生資料，動詞分別描述如下：

   • Get 讀取資源
   • Post 新增替源或作為utility API，例如檢查帳號是否存在
   • Delete 刪除資源
   • Put 替換單一資源
   • Patch 更新資源部份內容

3. Content Types 資源呈現方式

   當我們如果要取得某一個 API 的資料，此資料格式可以有 HTML、 XML、JSON 等格式，同樣的 URL 資源可以有不同型態的表現方式。

4. HTTP 回傳狀態碼

   API 回傳結果應使用正確的 HTTP 狀態碼，這樣呼叫者才可以了解 API 實際運行狀況，這邊整理常見的狀態碼，若要了解完整狀態碼說明可參考 wiki－List of HTTP status codes：

   • 2xx 成功運行
     • 200－OK 成功回傳結果
     • 201－Created 資源新增成功
     • 202－Accepted 請求接受，但結果還在處理
     • 204－No Content 沒有回應任何內容
   • 3xx 重新導向
     • 301－Moved Permanently 重新導向URI
     • 304－Not Modified 請求資源並未修改
   • 4xx 用戶端錯誤
     • 400－Bad Request 錯誤請求
     • 401－Unauthorized 使用者尚未通過身份驗證
     • 403－Forbidden 用戶端被禁止使用此請求
     • 404－Not Found 請求資源不存在
     • 405－Method Not Allowed 不支援請求的 Http method
     • 414－Url Too Long URI太長
   • 5xx 伺服器錯誤
     • 500－Internal Server Error 內部伺服器錯誤

   這邊也推薦大家可以參考 HTTP DECISION DIAGRAM 來了解每個 Http 狀態運行的活動圖，下圖僅擷取 Request 時的活動圖給予大家進行參考，如果有興趣可以前往觀看完整版。
   

而我們在 Controlelr 中加入的 @RestController 其實是 @Controller + @ResponseBody 組成，@Controller 是將標注（Annotation）的類別注入到 Spring IOC 容器，會讓該類別在運行中會被實例化（Instance），表示該類別具有 Controller 功用，而 @ResponseBody 會將我們函數所回傳的結果轉換為 JSON 格式傳送給 client 端。

這篇文章希望大家能夠先將API概念與RESTful設計概念了解清楚，明日將會介紹前面實作的專案加入 RESTful API 設計風格後的成果

Reference

• API 到底是什麼？ 用白話文帶你認識
• RESTful API 設計準則與實務經驗
• HTTP Status Codes Decision Diagram – Infographic